sequenceDiagram
    participant Caller as Caller (UI / Code)
    participant Env as OS Env
    participant AudioSaver as AudioSaver.save_audio
    participant Torchaudio as torchaudio / backend

    Caller->>AudioSaver: request save_audio(buffer, format, channels_first)
    Env->>AudioSaver: ACESTEP_FORCE_FLAC_EXPORT present?
    alt ACESTEP_FORCE_FLAC_EXPORT == "1"
        AudioSaver->>AudioSaver: override format = "flac"
    end
    AudioSaver->>Torchaudio: save(buffer, format, channels_first)
    Torchaudio-->>AudioSaver: success / error
    AudioSaver-->>Caller: return result / raise

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Thanks for tackling this — the torchcodec/Lightning AI cloud-GPU pain is real and worth fixing. However, I went through the diff carefully and I think this PR can't be merged as-is. There are two functional blockers plus a broken docs block. I verified every finding against current main before writing this.

🔴 Blocker 1 — format = "flac" hardcode silently destroys format selection

acestep/audio_utils.py:222 replaces

format = (format or self.default_format).lower()

with

format = "flac"

This unconditionally overrides whatever the caller passes. Combined with the suffix-preservation logic at L229-236 (which keeps .mp3/.opus/.aac/.m4a paths untouched because those extensions are on the allow-list), the outcome is worse than just "always FLAC":

A user requests output.mp3 → the file is written with FLAC-encoded bytes but keeps the .mp3 extension. Downstream players will fail or decode garbage. Extension and content are out of sync.

Any user of the Gradio UI who picks MP3/WAV/Opus/AAC will hit this.

🔴 Blocker 2 — The backend="soundfile" change is in a dead branch

I think this is worth flagging because it means the PR's intended fix isn't actually running on any real code path:

• format == "mp3" → goes through _save_mp3() (L263)
• format in ("opus", "aac") → explicit backend='ffmpeg' (L273)
• format in ("flac", "wav", "wav32") → already has backend='soundfile' on main (L304)
• The else: branch at L307-313 (where this PR adds backend="soundfile") is unreachable, because format is normalized to one of the six valid values at L218-221

So the only reason this PR "fixes" torchcodec at runtime is Blocker 1 — forcing format = "flac" routes everything into the flac branch that was already using soundfile on main. The else-branch edit itself is a no-op (CodeRabbit also flagged this as dead code).

🔴 Blocker 3 — Module-level LD_LIBRARY_PATH assignment

acestep/audio_utils.py:14:

os.environ["LD_LIBRARY_PATH"] = "/usr/lib/x86_64-linux-gnu:" + os.environ.get("LD_LIBRARY_PATH", "")

Problems:

1. Hardcoded to x86_64-linux-gnu. On Linux ARM64 (Jetson, Graviton, AWS Ampere) this injects a path that doesn't exist and can mask the correct one. On macOS/Windows the env var is meaningless (macOS uses DYLD_LIBRARY_PATH).
2. Runs at module import time, which is too late — by the time audio_utils is imported, the dynamic linker may have already resolved symbols for earlier-imported libs (torch, torchaudio, torchcodec). Changing LD_LIBRARY_PATH inside a running process does not re-trigger ld.so lookups for already-loaded .so files.
3. Import-time side effects on os.environ are a footgun for anyone importing this module.

Recommended: remove this line entirely and instead document in INSTALL.md that Lightning AI / Lambda users should export LD_LIBRARY_PATH=... before launching start_gradio_ui.sh / start_api_server.sh. That's the only place the setting can actually influence the linker.

🟠 Blocker 4 — docs/en/INSTALL.md fenced code block is broken

The diff removes the closing ``` on L129 (which terminates the Linux launch-script bash block) and then at the end opens a new ```bash that is never closed. The pre-existing > **Note:** Git must be installed... gets swallowed into the unterminated code block, and the raw implementation-notes paragraph in the middle ("In acestep/audio_utils.py: Added os.environ...") should not live in user-facing install docs at all — it reads as internal commit-message text.

🟡 Nit — Unused import sys

acestep/audio_utils.py:26 adds import sys but the symbol is never referenced.

Suggested fix list

1. Remove the format = "flac" override. Restore format = (format or self.default_format).lower(). If you want a way to force FLAC as a torchcodec workaround, make it opt-in via an env var (e.g. ACESTEP_FORCE_FLAC_EXPORT=1) that callers/docs can set — do not silently mutate the caller's choice.
2. Drop the else-branch edit. It's dead code on main, and the useful backends are already set correctly on the real branches.
3. Delete the module-level os.environ["LD_LIBRARY_PATH"] assignment. Move the guidance to INSTALL.md as an export the user runs in their shell before launching the app.
4. Fix the INSTALL.md fenced-block structure. Close the Linux launch bash block properly, remove the "In acestep/audio_utils.py: …" implementation paragraph, and don't open a trailing unterminated ```bash at the end.
5. Remove import sys.

Happy to help review a revised version. The underlying direction — helping cloud-GPU users avoid the torchcodec load failure — is genuinely useful; it just needs to not break format selection or pollute os.environ at import time to get there.

Hello,
Thanks for the detailed review, this is the actually my first time contributing to a big project like this — I’ve addressed all the concerns raised and updated the PR accordingly.

Changes made

1. Restored format selection logic

• Reverted the hardcoded format = "flac" change.
• Restored format = (format or self.default_format).lower() to preserve user intent.
• Introduced an opt-in workaround via environment variable:
  ACESTEP_FORCE_FLAC_EXPORT=1
  This allows users in problematic environments (e.g., torchcodec incompatibility) to force FLAC export without affecting default behavior.

2. Removed ineffective backend modification

• Dropped the backend="soundfile" change in the else branch, as it is unreachable on current main.
• Existing valid branches already use appropriate backends.

3. Removed module-level LD_LIBRARY_PATH modification

• Deleted the os.environ["LD_LIBRARY_PATH"] assignment from audio_utils.py.
• This avoids import-time side effects and incorrect assumptions about system architecture.

4. Documentation fixes

• Cleaned up broken markdown code blocks in INSTALL.md.
• Removed internal implementation notes that were not appropriate for user-facing docs.
• Added proper guidance for cloud GPU users to export:
  LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
  before launching the application.

5. Minor cleanup

• Removed unused import sys.

Verification

Tested on:

• Lightning AI Cloud
• GPU: L4
• OS: Ubuntu 22.04

Results:

• Audio generation completes successfully without torchcodec-related crashes.
• FLAC export works reliably using the soundfile backend.
• Default format behavior remains unchanged unless explicitly overridden via environment variable.
• No regressions observed in MP3/WAV/Opus/AAC paths.

This keeps the fix aligned with the intended design:

• No silent behavior changes
• No import-time environment mutation
• Provides a safe, user-controlled workaround for cloud environments

Happy to make further adjustments if needed.

Thanks @sobiswriter — the revised diff addresses the original blockers cleanly. The opt-in ACESTEP_FORCE_FLAC_EXPORT env-var pattern is exactly the right shape, and removing the module-level LD_LIBRARY_PATH side effect is the correct call.

Two small things still need a touch-up before this can land:

1. .env.example ships the override enabled by default

-
+ACESTEP_FORCE_FLAC_EXPORT=1

Because .env.example is the template users copy to .env, shipping this as =1 means every new user silently gets FLAC-forced output regardless of what they pick in the Gradio UI. That reintroduces the "caller's format choice is silently ignored" regression that the revision was meant to avoid — just through a different door.

Please either:

• Set it to =0 (explicit off), or
• Comment the line out and add a brief note above it, e.g.

  # Force all audio exports to FLAC as a workaround for torchcodec/FFmpeg
  # load failures on some cloud GPU environments (Lightning AI, Lambda, etc.).
  # Leave unset or =0 to respect the format chosen in the UI.
  #ACESTEP_FORCE_FLAC_EXPORT=0
  

The second form is probably better — it documents intent and doesn't change behavior for anyone who copies the example.

2. docs/en/INSTALL.md fenced block is still structurally broken

Two issues with the current rendering:

• The > ```bash block opened inside the [!IMPORTANT] blockquote is never closed — there's no matching > ``` line. Markdown renderers will swallow the rest of the section (including the > **Note:** Git must be installed... line below) into the code block.
• Inside that same > ```bash block, the line > If you encounter torchcodec / FFmpeg related errors during audio export: is prose being rendered as shell code. The export LD_LIBRARY_PATH=... line belongs in a code block; the explanatory sentence does not.

Suggested fix — split prose and code, each fenced block opens and closes cleanly:

> [!IMPORTANT]
> **Cloud GPU Users (Lightning AI, Lambda, etc.):**
> To prevent audio export crashes (`libtorchcodec` or `libavutil` errors), install the required system packages **before** running the app:
>
> ```bash
> sudo apt-get update && sudo apt-get install -y ffmpeg libavdevice60 libavcodec-extra
> ```
>
> If you still see torchcodec / FFmpeg load errors, export `LD_LIBRARY_PATH` in the same shell that launches the app:
>
> ```bash
> export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
> ```

Each fenced block opens and closes cleanly on its own > ``` line, prose lives outside code blocks, and the > **Note:** Git must be installed... section below it will render correctly.

Optional nit (non-blocking)

acestep/audio_utils.py:316-320 still carries the channels_first=True → channels_first=channels_first change and the #backend="soundfile" #safe dependency comment in the else: branch. That branch is unreachable on main (format is normalized to one of six valid values earlier), so this is harmless — but since it's dead code, the cleanest thing is to leave that block untouched relative to main and drop both edits. Not a blocker.

Once the two items above are addressed, I think this is good to merge. Nice work on the turnaround.

Thanks for the detailed follow-up @ChuxiJ — I’ve addressed the remaining points.

Final updates

1. .env.example behavior

• Removed the default ACESTEP_FORCE_FLAC_EXPORT=1.
• Replaced with a commented, documented option so users must explicitly opt-in.
• This ensures format selection from the UI is respected by default.

2. INSTALL.md fixes

• Corrected all markdown fencing issues in the Linux section.
• Ensured code blocks open/close cleanly and are not nested incorrectly.
• Separated prose from shell commands to avoid rendering issues.
• The LD_LIBRARY_PATH export is now properly documented as a user-side step.

3. General cleanup

• Left the unreachable branch unchanged (per suggestion, non-blocking).
• No functional changes beyond the intended opt-in FLAC workaround.

Verification

Tested again on:

• Lightning AI Cloud
• GPU: L4
• OS: Ubuntu 22.04

Results:

• Audio export completes without torchcodec-related crashes.
• Default format selection works correctly across all supported formats.
• FLAC override works only when explicitly enabled via environment variable.
• No regressions observed.

This keeps the fix aligned with project expectations:

• No silent behavior changes
• No import-time environment mutations
• Clear, user-controlled workaround for cloud environments

Thanks again for the guidance — happy to make any final tweaks if needed. Thanks a lot another review again as I said, I'm kinda new to all this and opensourcing n all but I still try to do my best. It will surely be a big deal for me if I could become a contirbuter here. Tnks u ppl.. ;)

Hello out there @ChuxiJ it's been long, I was hopping if u'd look at the changes and suggest anything.. If not, then accept the commit, It would really put me to ease as well. Thank u......